/*
	Visp is a visual performance application (VJ app) built on Adobe's AIR runtime framework.
	Copyright (C) 2007 Mike Creighton
	
	This program is free software; you can redistribute it and/or
	modify it under the terms of the GNU General Public License
	as published by the Free Software Foundation; either version 2
	of the License, or (at your option) any later version.
	
	This program is distributed in the hope that it will be useful,
	but WITHOUT ANY WARRANTY; without even the implied warranty of
	MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
	GNU General Public License for more details.
	
	You should have received a copy of the GNU General Public License
	along with this program; if not, write to the Free Software
	Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, USA.
	
	Mike Creighton can be found at http://www.mikecreighton.com	
*/
package com.visp.filters
{
	import flash.display.BitmapData;
	import flash.geom.ColorTransform;

	/**
	 * It is crucial that your filter extends the com.visp.filter.FilterBase
	 * class since it contains much of the required functionality needed
	 * for alpha transparency of your filter's output.
	 * 
	 * Note that you'll have access to a protected property called _source
	 * which is a BitmapData instance. In the FilterBase ancestor, the 
	 * contents of this BitmapData instance will get copied over the top of 
	 * the final output bitmap.
	 */
	public class AlphaTrailFilter extends FilterBase
	{
		private var _feed : BitmapData;
		private var _feedTrans : ColorTransform;
		
		/**
		 * Though not explicitly present in this class, there is a statement
		 * in FilterBase:
		 * 
		 * 		protected var _source : BitmapData;
		 * 
		 * This _source variable is available to your filter as a BitmapData
		 * canvas for doing your dirty work.
		 */
		
		
		/**
		 * Initializes all the instance variables outside of BitmapData objects.
		 * You must call super().
		 */
		public function AlphaTrailFilter()
		{
			super();
			// We're creating our own ColorTransform of copying our
			// bitmap data to cause the alpha trail effect
			this._feedTrans = new ColorTransform(1, 1, 1, 1);
		}
		
		/**
		 * Instantiates all needed bitmapData objects. It's very important
		 * to pass the sourceBitmapData instance onto the ancestor's
		 * initalize() method. This will make a copy of this BitmapData
		 * and assign it to the protected _source BitmapData instance.
		 * 
		 * The _source BitmapData instance is your filter's canvas for
		 * applying its visual effect.
		 */
		override public function initialize(sourceBitmapData : BitmapData) : void {
			super.initialize(sourceBitmapData);
			
			// We're creating a BitmapData instance to do some copying of pixels.
			this._feed = new BitmapData(this._source.width, this._source.height, true, 0x00000000);
		}
		
		/**
		 * This is the main method that gets called when your filter is active
		 * after the renderer has drawn its frame. The inputBitmapData represents
		 * that renderer output. This is a "live" instance, so anything you do
		 * to this BitmapData reference is what will be used as the final
		 * output in visp.
		 * 
		 * By calling super.apply(inputBitmapData), the FilterBase ancestor
		 * will copy the contents of the _source BitmapData onto the inputBitmapData
		 * based on the current "alpha" value that has been set by the filter's
		 * accompanying UI component.
		 */
		override public function apply(inputBitmapData:BitmapData) : void
		{
			if(this._feedTrans.alphaMultiplier > 0){
				// Grab the input and copy it to our _source based on
				// the current opacity of our _feedTrans ColorTransform.
				this._source.draw(inputBitmapData, null, this._feedTrans);
			}
			
			// Apply the standard alpha opacity copy
			super.apply(inputBitmapData);
		}
		
		/**
		 * The updateAlpha() funciton is a common function that all filters share.
		 * This function is called by the InputManager when input (via UI or MIDI) is
		 * received -- with the ID of the generic FilterRange.ID_GENERIC_ALPHA.
		 * 
		 * We'll pretty much always not override this method since our FilterBase 
		 * ancestor handles the alpha transparency of the filter itself.
		 */
		/*
		override public function updateAlpha(value:Number):void { }
		*/
		
		/**
		 * The updateValue1() function is a common function that all filters share. This
		 * function is called by the InputManager when input (via UI or MIDI) is
		 * received -- with the ID of the generic FilterRange.ID_GENERIC_0.
		 * 
		 * Makes changes to the FEED alpha (i.e. how much onion skinning we see)
		 */
		override public function updateValue1(value:Number):void
		{
			// We actually want to invert the incoming value to achieve
			// the desired effect.
			this._feedTrans.alphaMultiplier = 1 - value;
		}
		
		/**
		 * The updateValue2() function is a common function that all filters share. This
		 * function is called by the InputManager when input (via UI or MIDI) is
		 * received -- with the ID of the generic FilterRange.ID_GENERIC_1.
		 * 
		 * In this particular case, we're not responding to anything.
		 */
		override public function updateValue2(value:Number):void
		{
			// trace("Value update 2: " + value);
		}
		
		/**
		 * This gets called when a filter is being removed from the filter stack
		 * in visp. It is a best practice to dispose of all bitmaps and generally
		 * handle your memory management needs here.
		 */
		override public function destroy() : void
		{
			// Dispose of our bitmap
			this._feed.dispose();
			
			// Calling super.dispose() gets rid of our _source BitmapData.
			super.destroy();
		}
	}
}